Skip to content

feat(ce-brainstorm, ce-plan): unify brainstorm and plan into one readiness-staged artifact#972

Draft
tmchow wants to merge 29 commits into
mainfrom
tmchow/feat-unified-brainstorm-plan-docs
Draft

feat(ce-brainstorm, ce-plan): unify brainstorm and plan into one readiness-staged artifact#972
tmchow wants to merge 29 commits into
mainfrom
tmchow/feat-unified-brainstorm-plan-docs

Conversation

@tmchow

@tmchow tmchow commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

Summary

ce-brainstorm and ce-plan now produce one artifact in docs/plans/ that moves through readiness states, instead of a brainstorm requirements doc plus a separate plan doc. ce-brainstorm writes a requirements-only skeleton; ce-plan enriches that same file in place to implementation-ready; and every downstream reader is readiness-aware, so a requirements-only skeleton can no longer be mistaken for executable work. Legacy docs/brainstorms/*-requirements.* inputs and origin: references keep resolving indefinitely — nothing is migrated.

The win: the implementing agent reads one durable authority (scope, decisions, verification, done criteria) instead of stitching two files, and requirement changes can't drift away from the plan that executes them.

The artifact contract

A unified plan carries readiness as document-completeness metadata — never a mutable work-progress status:

Field Meaning
artifact_contract: ce-unified-plan/v1 Declares the contract
artifact_readiness: requirements-only | implementation-ready Can the artifact be executed yet — not whether execution happened
product_contract_source: ce-brainstorm | ce-plan-bootstrap | legacy-requirements Where the Product Contract came from

Fixed section order (Goal Launch Block, Reader Index, Goal Capsule, Product Contract, then — when implementation-ready — Planning Contract, Implementation Units, Verification Contract, Definition of Done) with a stable Section ID Registry so consumers grep before reading the whole file.

Design decisions worth a look

  • The document is the authority; the Goal Launch Block is a thin launcher. It routes and points into the body — it does not duplicate requirements or verification. Over a long /goal run the prompt is summarized away, so durable scope must live in the doc.
  • No mutable status: lifecycle. Readiness answers "executable?", not "done?"; progress stays in git, task trackers, and commits. Tests reject progress-like values (active, in_progress, completed, done).
  • ce-work gained an execution-engine lane (skills/ce-work/references/execution-engines.md): inline/subagent (default, and the only callable engine on Claude Code) vs goal-mode vs dynamic-workflow, gated on a host-capability probe, with explicit resume-the-correct-tail rules. A caller-owned-tail mode lets lfg own simplify/review/PR/CI while ce-work owns implementation strategy.
  • Readiness-aware downstream routing. Blank ce-work won't auto-execute a requirements-only/knowledge-work/approach-plan artifact; ce-doc-review classifies by readiness and reviews Product vs Planning Contract by section slice instead of sending the whole artifact to every persona; ce-code-review classifies readiness before flagging unit completeness; ce-proof publishes markdown only.
  • Goal-mode refinements from OpenAI's /goal guide by Dominik Kundel (readable mirror): prefer measurable exit thresholds for optimization-shaped goals, and require dead-end/experimental-code cleanup before "done." The Codex draft-PR progress pattern is deliberately not adopted — it conflicts with the rule that the goal never opens a PR.

Validation

Non-observable change (skill prose, references, tests, docs — no runtime UI/CLI surface), so no demo artifact. Verified against current main:

  • bun test1600 pass, 0 fail (includes a new unified-plan-artifact-contract suite and added HTML nav/anchor invariants).
  • bun run release:validate — metadata in sync (0 agents, 27 skills).

Rebased onto main's skills-only / root-native refactor (#967); all changes are root-native under skills/, docs/, and tests/.


Compound Engineering
Claude Code

@tmchow tmchow marked this pull request as draft June 22, 2026 17:25

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 51a84d91da

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread skills/lfg/SKILL.md Outdated
Comment thread skills/ce-code-review/SKILL.md
Comment thread skills/ce-plan/SKILL.md Outdated
tmchow added a commit that referenced this pull request Jun 22, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow added a commit that referenced this pull request Jun 22, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
@tmchow tmchow changed the title feat: unify brainstorm and plan into one readiness-staged artifact feat(ce-brainstorm, ce-plan): unify brainstorm and plan into one readiness-staged artifact Jun 23, 2026
tmchow added a commit that referenced this pull request Jun 23, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow added a commit that referenced this pull request Jun 23, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
@tmchow tmchow force-pushed the tmchow/feat-unified-brainstorm-plan-docs branch from b5589eb to 9348929 Compare June 23, 2026 07:49
@tmchow tmchow marked this pull request as ready for review June 23, 2026 18:43
@tmchow

tmchow commented Jun 23, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@tmchow tmchow marked this pull request as draft June 23, 2026 18:44

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9348929e20

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread skills/ce-plan/references/plan-sections.md Outdated
tmchow added a commit that referenced this pull request Jun 24, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow added a commit that referenced this pull request Jun 24, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
@tmchow tmchow force-pushed the tmchow/feat-unified-brainstorm-plan-docs branch from 3f2ed8f to c7b430a Compare June 24, 2026 07:12
tmchow added a commit that referenced this pull request Jun 24, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow added a commit that referenced this pull request Jun 24, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
@tmchow tmchow force-pushed the tmchow/feat-unified-brainstorm-plan-docs branch from c7b430a to 03965a7 Compare June 24, 2026 19:07
tmchow added a commit that referenced this pull request Jun 24, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow added a commit that referenced this pull request Jun 24, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
@tmchow tmchow force-pushed the tmchow/feat-unified-brainstorm-plan-docs branch from 03965a7 to bf283d9 Compare June 24, 2026 21:24
tmchow added 8 commits June 24, 2026 14:56
Add the execution-engine selection lane that the unified-plan refactor
specified but under-implemented: a references/execution-engines.md covering
host-capability probing, goal-mode/dynamic-workflow vs inline/subagent
selection, copyable /goal and ultracode: prompts, and resume-correct-tail
rules; wire a concise engine-selection step into ce-work Phase 1.

Reconcile reference drift left by the refactor: ce-plan synthesis-summary
and ce-doc-review synthesis-and-presentation now describe the unified
Product/Planning Contract nesting and readiness-aware next-stage routing;
align the plan doc's legacy product_contract_source value.

Adopt two refinements from Kundel's /goal guide: prefer measurable exit
thresholds for optimization-shaped goals, and require dead-end/experimental
code cleanup before done. Add HTML nav/id and contract-test coverage for the
above.
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
  lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
  Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
  unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
- execution-engines: add a Codex lane (top-level /goal is a thread mode,
  not an awaitable nested engine), a progress-visibility lane independent
  of final-PR tail ownership, and a compaction re-read instruction
- plan-sections: Goal Launch Block must be evaluator-complete (prompt is
  also the completion criteria) and split human vs pipeline launch;
  implementation-ready requires zero launch-blocking open questions;
  markdown is the canonical execution artifact, HTML is report-only
- ce-plan: record a Product Contract preservation note on in-place
  enrichment so the WHAT/HOW review boundary stays visible
- plan doc: fix its own Goal Launch Block to reference sections it has
  (it is a pre-contract meta-plan) and mark open questions non-blocking
- contract tests cover all of the above
…ption

The post-plan menu offered no way to get the copyable /goal prompt on
hosts where ce-work is skill-invocable (Claude Code) — picking 'Start
/ce-work' ran the skill instead. Verified (claude-code-guide + Codex's
own docs) that a skill cannot invoke /goal on either platform; it can
only emit a copyable prompt. So /goal becomes its own menu option,
mutually exclusive with 'Start /ce-work' (only one executor runs the
plan — tail-ownership guard), gated to implementation-ready code plans
and opt-in so the long prompt never auto-dumps.

Also make the menu-rendering guidance declarative — drop the runtime
'Per the AGENTS.md' authoring-file reference. Contract tests cover the
new option, the mutual-exclusion guard, and the absence of the meta-ref.
tmchow added 17 commits June 24, 2026 14:56
- drop the 'Done for now' option from both the ce-plan and ce-brainstorm
  handoff menus — the blocking question already waits, so pausing is
  implicit (dismiss/Esc or say you're finished); the artifact is saved
  either way. ce-brainstorm's closing summary still fires on the natural
  finish/dismiss path.
- reword 'Start /ce-work' to plain user language ('Implement this plan
  now, in this session') instead of the internal 'owns the tail' jargon
- gate the 'Give me the /goal prompt' option to hosts that actually have
  a top-level /goal command (Claude Code and Codex); omit it elsewhere
'Run deeper doc review' didn't say what it does. Rename it to 'Review
remaining findings' and rewrite the description to explain the model:
the auto-pass already applied the safe mechanical fixes; this option
walks through what it left for the user's judgment — proposed edits that
change the plan's meaning/scope (confirm or skip) and judgment calls
with no single right answer (decide, or defer into Open Questions).
Renamed the routing-key references in lockstep.
…view's open items'

'Review remaining findings' still didn't signal the user has decisions to
make. Rename to 'Decide on the review's open items' with a plain secondary
line ('Confirm or skip the suggested edits, and settle the judgment calls
the auto-pass left for you'). Routing-key references and tests updated in
lockstep.
…enus

ce-brainstorm: rename the menu to plain actions and add a skip-planning
path that doesn't force ce-work. One slot renders the most autonomous
available option — 'Create a /goal prompt' on /goal hosts (Claude Code,
Codex), else 'Build it now' via ce-work — never both, since at the
requirements stage choosing between them is confusing. ce-plan stays the
recommended path (sharpest requirements, least rework). Rename the
'Agent review of Product Contract' option to 'Pressure-test the
requirements' — at this stage no review has run yet, so it is the first
critique, not adjudicating leftovers.

ce-plan: both ce-work and /goal stay shown (the plan is real, so it's a
preference), with descriptions that state the deciding factor — shorter
work / watch-and-steer vs longer / autonomous-to-DoD. Rename 'Give me the
/goal prompt' to 'Create a /goal prompt' for consistency.

Wording informed by asking Codex (the /goal authority) why one picks
/goal vs a direct implement instruction. Tests updated for all renames.
The (recommended) marker is now dynamic: /goal carries it when the host
has a top-level /goal command (Claude Code, Codex); ce-work carries it
otherwise (when the /goal option is omitted). Exactly one option is ever
marked. Reflects that the autonomous run-to-DoD is the preferred default
when available, with ce-work as the in-session fallback.
…opy-paste

Corrects a wrong claim in execution-engines.md. Confirmed empirically:
a Codex skill CAN start goal-mode via the create_goal tool (gated by
features.goals); Claude Code exposes no goal tools at all. So:

- execution-engines.md: goal-mode is a callable engine where a goal tool
  exists. create_goal sets+activates the objective and the CURRENT session
  works toward it (not a background worker, no awaitable envelope). The
  skill does NOT call update_goal — the goal session marks its own
  completion. create_goal is standalone-only, never caller-owned-tail
  (which must return control).
- ce-plan and ce-brainstorm /goal options: on a callable-goal-tool host,
  selecting it calls create_goal directly (no copy-paste); on a
  user-typed-/goal host (Claude Code) it emits the copyable prompt; ce-work
  never also runs. ce-brainstorm's skip-planning slot falls back to ce-work
  only where there is no goal mode at all.

The literal /goal slash command remains user-typed-only everywhere; the
tool path is what makes Codex callable. Tests updated.
'Create a /goal prompt' implied a copy-paste prompt, but on a host with a
callable goal tool (Codex create_goal) there is no prompt — the session
just starts. 'Run it as a /goal' is truthful for both paths (direct start
or copy-paste), with the mechanism in the description. One label, one
routing key, across ce-plan and ce-brainstorm. Tests updated.
Rebase reconciliation: keep main's capability-based tracker routing and
its category-style menu label (e.g., GitHub Issues, Linear, Jira) instead
of the closed '(GitHub or Linear)' set, satisfying main's new contract test.
Real-run feedback on a ce-brainstorm output surfaced three packaging issues:

- No hard-wrapping: add a markdown-rendering rule (all copies) — don't wrap
  prose to a fixed column; one sentence per line or let it flow. Fixed wraps
  only make noisy diffs and never change rendered output.
- Slim the requirements-only skeleton for standalone readability: Goal Launch
  Block is now a single next-step line (no 'don't run ce-work/goal' lecture or
  stop-condition prose — the frontmatter carries that for agents); drop the
  Reader Index entirely (nothing to route across two sections); Goal Capsule
  keeps objective/authority/blockers only. ce-plan adds the Reader Index and
  implementation scaffolding when it enriches to implementation-ready.
- Title is '<Name> - Plan' (stable across readiness; it is a unified plan at
  every stage), matching the H1; no conventional-commit prefix in the title —
  the type field carries that. Reconciled the contract example accordingly.

Tests updated.
The launch prompt was a doc section baked into every artifact, so it went
stale as the template evolved (we iterated it ~5x), duplicated logic already
in the skill, and cluttered a doc meant to communicate the plan. It is now
generated at handoff from a single living source — ce-work's
execution-engines.md template — printed as a copyable /goal on Claude Code or
started via create_goal on Codex; ce-plan's menu builds the objective from the
plan's current content. Docs keep the durable authority (content, metadata,
and — implementation-ready only — Reader Index + Goal Capsule navigation).

Removed Goal Launch Block from the Section ID Registry, both section
contracts, all markdown/html rendering refs (parity kept), the brainstorm
skeleton, and the ce-plan menu routing. An agent invoked on a doc executes
from frontmatter + content + its own current reader strategy, so nothing is
lost. Tests updated.

Note: the historical meta-plan doc still describes the old baked section; it
is a planning record, not the live contract (the skill refs are).
The unified-plan meta-plan still described a baked Goal Launch Block doc
section and the older 'goal-mode is an awaitable callable that returns a
summary' model. Reconcile it in place to match what shipped: the launch prompt
is skill-emitted at handoff (copyable /goal on Claude Code, create_goal on
Codex) from ce-work's execution-engines.md; create_goal steers the current
session (standalone only, never caller-owned-tail); requirements-only artifacts
are slim (Goal Capsule + Product Contract, no Reader Index); and there is no
Goal Launch Block in the contract, registry, rendering anchors, or section
semantics. Retitled the meta-plan's own launch section to a retained record.
The Reader Index was a hand-maintained pseudo-TOC baked into every artifact:
its map duplicated a one-line heading scan, its 'when to read' column was
generic boilerplate identical across plans, and it could drift from the real
headings — the same anti-pattern as the baked launch prompt. Drop it from the
contract, registry, rendering refs (markdown + HTML), brainstorm skeleton,
ce-plan enrichment, and the meta-plan.

Wayfinding now lives entirely in the consuming skills and is hardened: never
reflexively read the whole artifact; build a section map and read only the
needed ranges. Made it explicit for BOTH formats — markdown heading scan
(rg '^#{1,3} ') and HTML <h1>-<h3>/anchor-id scan — and anchored it to the
Section ID Registry's stable names so it survives rendering changes rather
than a brittle tag pattern. Made it size-aware: a short plan (lightweight or
requirements-only) is read in full; the map-and-range discipline is for long
implementation-ready plans where a full read wastes context. Updated ce-work,
ce-work-beta, execution-engines, ce-doc-review, plan-handoff, and tests.
…opies it

The emitted /goal prompt was over-stuffed: it duplicated the plan's resolved
decisions (shortcut, palette), exact verification commands, and an enumerated
read order (including the now-removed Reader Index) into the prompt. Per the
goal model (direction + exit criteria + a few persistent guardrails; durable
detail stays in the doc), that copied content only ages and drifts.

Update the emission template (execution-engines.md canonical prompt, plus the
ce-plan handoff routing and SKILL inline) to:
- keep the prompt thin and point to the plan's sections — explicit guardrail
  not to copy resolved decisions, exact commands, or requirements into it;
- reference the Verification Contract gates rather than inlining commands;
- keep the persistent guardrails (own the tail, do not open a PR, track
  progress outside the plan file);
- sharpen the blocker rule: surface a genuine blocker (changes scope or
  contradicts the plan), but use judgment on details the plan leaves open —
  so the goal doesn't over-stop and defeat its autonomy.

Tests updated for the new phrasing.
…ller

`caller-owned-tail` described the internal mechanic (who owns the post-impl
'tail') in jargon. `return-to-caller` says what the mode does: ce-work
implements and locally verifies, then hands control back to the caller (lfg)
instead of running simplify/review/PR/CI. Renamed the flag, the prose, and the
SKILL section heading across ce-work, lfg, execution-engines, and the meta-plan.

ce-work's parser still recognizes the legacy `mode:caller-owned-tail` token (and
`caller:lfg`) as aliases so an in-flight reference doesn't break. Tests updated.
…ning /goal

The brainstorm Phase 4 menu's autonomous slot was a skip-planning /goal —
implement straight from requirements with no planning step, which its own label
admitted was likelier to need rework. Replace it with lfg: the full autonomous
pipeline that plans first (ce-plan), implements, simplifies, runs independent
code review and applies fixes, opens a PR, and watches CI. It's the safer
autonomous path (plans before building) and matches how lfg is actually run
after brainstorm. Routing invokes lfg with the plan path so its ce-plan step
enriches this artifact in place rather than bootstrapping a new one; gated to
software (execution: code) with Resolve Before Planning empty.

A raw /goal remains reachable post-planning at the ce-plan handoff. Updated the
option-counting/gating prose (removed the skip-planning/direct-to-work machinery)
and tests.
Reworked the subagent-dispatch section after probing Codex and Cursor for their
actual subagent mechanics. The old guidance was Claude-shaped (isolation:
worktree, .claude/worktrees, git-worktree merge) and didn't fit Codex
(spawn_agent worker + 'uploaded changes') or Cursor (Task, shared workspace /
best-of-n) — and it framed parallelism as a rare opt-in rather than the goal.

- Lead with the throughput-forward principle: prefer subagents for multi-unit
  plans, parallelize independent units whenever safe; the plan's
  Dependencies/Files drive batching. Drop the arbitrary '3+' thresholds.
- Capability-based isolation, never hand-rolled: ce-work never runs
  'git worktree add'; isolation is the harness's job (Claude Agent worktree,
  Codex forked workspace, Cursor best-of-n) — works fine from inside an existing
  worktree (peers, not nested). No native isolation -> shared workspace,
  disjoint files only.
- Correctness fixes: overlap is recoverable, not safe (serialize unless merge is
  trivial); file overlap is necessary-not-sufficient (also serialize on shared
  types/migrations/lockfiles/snapshots/generated/config and environment
  singletons); concurrency cap (~3-5); abort criteria.
- Orchestrator owns commits/merge/verification everywhere; workers implement +
  report changed paths + optional isolated self-test, never commit (confirmed
  safe on both probed harnesses — work persists for the orchestrator). The
  orchestrator inspects the actual tree, since the handoff is a summary with no
  guaranteed diff. Release worker handles (e.g. close_agent) on cleanup.
- Per-harness mechanics kept inline as labeled examples (not relocated), so an
  agent that doesn't read a reference still has the safe procedure.
Per the new 'Writing Skill Instructions' rule (#1000), trim no-op prose this
branch added: drop the 'shareable requirements doc, not an agent-scaffolding
dump' framing flourish (the include/exclude rules that follow already
operationalize 'light and standalone-readable'); drop the 'main benefit' and
'use workers aggressively, not minimize them' motivational tails from the
subagent lead (the 'parallelize whenever safe' directive stands alone); drop
dead intensifiers ('actually', 'simply') and the 'confirmed empirically'
evidence aside in execution-engines. No behavioral change.
@tmchow tmchow force-pushed the tmchow/feat-unified-brainstorm-plan-docs branch from 5ae06b7 to 2d5d57a Compare June 24, 2026 22:01
tmchow added 4 commits June 24, 2026 15:05
Apply the deletion test to the launch-prompt-emission and brainstorm-write
prose added earlier in this branch:
- ce-brainstorm write step: drop the 'why' tail explaining the absent Goal
  Launch Block / Reader Index (the 'do not emit' directive + the reference
  pointer stand alone; the explain-the-absence rationale is a no-op).
- execution-engines copyable-prompt preamble: drop the 'they live in the doc, a
  copy drifts' rationale and the 'prompt carries direction... document carries
  the detail' restatement (the 'keep it thin / do not paste' directives stand).
- ce-plan SKILL + plan-handoff /goal routing: drop the 'they live in the doc
  and would drift' rationale parentheticals on the 'do not copy' directive.
No behavioral change; the directives and constraints are unchanged.
Port the capability-based subagent rewrite from ce-work into ce-work-beta
(it carried the pre-rewrite version): throughput-forward framing (parallelize
independent units when safe; drop the '3+' thresholds); capability-based
isolation that ce-work-beta never hand-rolls (Claude Agent worktree / Codex
spawn_agent worker / Cursor best-of-n; works from inside an existing worktree
as peers); Parallel Safety Check with semantic + environment-singleton
contention, recoverable-not-safe overlap, concurrency cap, abort criteria;
workers report changed paths and never commit; orchestrator inspects the actual
tree, owns commits/merge, and releases workers; per-harness integration kept
inline as examples.

Preserves beta's differences: the 'Choose Execution Strategy' heading, the
Codex delegation routing gate (references/codex-delegation-workflow.md), the
'not the primary unified-plan executor / mirror stable' framing, and beta's
subagent terminology. No new references introduced. Authoring rule applied.

Ported by a subagent; verified by the orchestrator (diff reviewed, scope
confirmed, bun test 1639/0 + release:validate re-run independently).
…copying plan specifics

A Codex run showed the emitted standalone /goal objective still copying plan
specifics (full U-ID dependency graph, exact verification commands, specific
stop conditions, DoD items) despite the 'do not copy' instruction — the
instruction wasn't operationalized enough, and 'emit verbatim' / 'build from the
plan' both invited embellishment.

- Operationalize the anti-copy rule with a deletion test the emitter applies to
  its draft: if it names a specific command, file path, U-ID dependency
  relationship, stop condition, or DoD item, cut it — the prompt should read
  identically for any plan except the substituted path. Applied in
  execution-engines (standalone prompt preamble), plan-handoff, and ce-plan SKILL.
- Drop the hardcoded 'Do not open a PR' from the STANDALONE /goal emission (and
  the matching 'no PR was opened' done-condition). A blanket no-PR overrides the
  repo's and user's PR conventions, which the executing agent already has via
  memory/AGENTS.md — let it decide. The emitter is told to add no PR directive
  either way. Structural no-PR is kept ONLY in return-to-caller mode (lfg owns
  the PR there).

Tests updated: the standalone-prompt no-PR assertions now check plan-agnostic +
no-PR-directive framing; the structural no-PR is asserted via return-to-caller.
…tegy, repo+user override

Removing the hardcoded no-PR left the standalone goal with no PR signal at all,
which could silently flatten a plan's deliberate PR/landing split (the strategy
lives in the Planning Contract, not the DoD, so 'implement to DoD' doesn't bind
it). Add a thin, plan-agnostic precedence line to the emitted prompt:

  Follow the plan's PR/landing strategy if it defines one; the repo's
  conventions and the user's preferences override it.

Precedence: explicit user instruction > repo/project conventions > user
preferences > the plan's strategy > agent default. Genuine conflicts are caught
by the existing 'contradicts the plan' blocker clause. Standalone only;
return-to-caller keeps the structural 'must not open any PR' (lfg owns the PR).
Applied in execution-engines, plan-handoff, and ce-plan SKILL; emission preamble
updated to carry the precedence line rather than a hardcoded open/don't-open
directive. Tests updated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant